/**
 * Software License, Version 1.0
 * 
 * Copyright 2008 The Trustees of Indiana University.  All rights reserved.
 * 
 *
 *Redistribution and use in source and binary forms, with or without 
 *modification, are permitted provided that the following conditions are met:
 *
 *1) All redistributions of source code must retain the above copyright notice,
 * the list of authors in the original source code, this list of conditions and
 * the disclaimer listed in this license;
 *2) All redistributions in binary form must reproduce the above copyright 
 * notice, this list of conditions and the disclaimer listed in this license in
 * the documentation and/or other materials provided with the distribution;
 *3) Any documentation included with all redistributions must include the 
 * following acknowledgment:
 *
 *"This product includes software developed by the Community Grids Lab. For 
 * further information contact the Community Grids Lab at 
 * http://communitygrids.iu.edu/."
 *
 * Alternatively, this acknowledgment may appear in the software itself, and 
 * wherever such third-party acknowledgments normally appear.
 * 
 *4) The name Indiana University or Community Grids Lab or Granules, 
 * shall not be used to endorse or promote products derived from this software 
 * without prior written permission from Indiana University.  For written 
 * permission, please contact the Advanced Research and Technology Institute 
 * ("ARTI") at 351 West 10th Street, Indianapolis, Indiana 46202.
 *5) Products derived from this software may not be called Granules, 
 * nor may Indiana University or Community Grids Lab or Granules appear
 * in their name, without prior written permission of ARTI.
 * 
 *
 * Indiana University provides no reassurances that the source code provided 
 * does not infringe the patent or any other intellectual property rights of 
 * any other entity.  Indiana University disclaims any liability to any 
 * recipient for claims brought by any other entity based on infringement of 
 * intellectual property rights or otherwise.  
 *
 * LICENSEE UNDERSTANDS THAT SOFTWARE IS PROVIDED "AS IS" FOR WHICH NO 
 * WARRANTIES AS TO CAPABILITIES OR ACCURACY ARE MADE. INDIANA UNIVERSITY GIVES
 * NO WARRANTIES AND MAKES NO REPRESENTATION THAT SOFTWARE IS FREE OF 
 * INFRINGEMENT OF THIRD PARTY PATENT, COPYRIGHT, OR OTHER PROPRIETARY RIGHTS. 
 * INDIANA UNIVERSITY MAKES NO WARRANTIES THAT SOFTWARE IS FREE FROM "BUGS", 
 * "VIRUSES", "TROJAN HORSES", "TRAP DOORS", "WORMS", OR OTHER HARMFUL CODE.  
 * LICENSEE ASSUMES THE ENTIRE RISK AS TO THE PERFORMANCE OF SOFTWARE AND/OR 
 * ASSOCIATED MATERIALS, AND TO THE PERFORMANCE AND VALIDITY OF INFORMATION 
 * GENERATED USING SOFTWARE.
 */
package cgl.granules.operation;

import java.io.IOException;
import java.util.Properties;

import cgl.granules.dataset.DatasetCollection;
import cgl.granules.dataset.DatasetException;

/**
 * This is the interface which encapsulates an application instance that will be
 * deployed. This interface allows access to several fields that play a role in
 * the deployment of application instances such as: domain, operation
 * identifier, instance identifier etc. Applications can also include support
 * for
 * 
 * @author Shrideep Pallickara
 * 
 */
public interface Operation {
	/**
	 * Retrieve the identifier associated with this operation.
	 * 
	 * @return The operation identifier
	 */
	public String getOperationIdentifier();

	/**
	 * Retrieve the instance identifier for this operation. Every time an
	 * instance is created, this identifier is automatically created. The value
	 * of the instance identifier can also be set.
	 * 
	 * @return The instance identifier for this operation.
	 */
	public String getInstanceIdentifier();

	/**
	 * Get information about the domain for this operation
	 * 
	 * @return The domain for this operation
	 */
	public String getDomain();

	/**
	 * A monotonically increasing version number needs to be associated with the
	 * operations. This allows the container to determine if the classes need to
	 * be reloaded.
	 * 
	 * @return The version number needs to be associated with this operation.
	 */
	public long getVersionInformation();

	/**
	 * Marshall this operation as a stream of bytes
	 * 
	 * @return The byte[] representation of the operation.
	 * @throws IOException
	 *             If there are problems Marshalling this operation.
	 */
	public byte[] getBytes() throws IOException;

	/**
	 * Unmarshall the operation from a set of marshalled bytes.
	 * 
	 * @param marshalledBytes
	 *            The byte[] representation of the operation.
	 * @throws IOException
	 *             If there are problems unmarshalling this operation.
	 */
	public void unmarshall(byte[] marshalledBytes) throws IOException,
			DatasetException;

	/**
	 * Checks to see if the operation has processing directives
	 * 
	 * @return <code>true</code> if the operation has processing directives;
	 *         <code>false</code> otherwise.
	 */
	public boolean hasProcessingDirectives();

	/**
	 * These properties encapsulate the set of processing directives that are
	 * needed to initialize the operation in question. Specifically, these
	 * directives are utilized by the operation to initialize the datasets that
	 * are needed by the operation.
	 * 
	 * @return The processing directives associated with the operation.
	 */
	public Properties getProcessingDirectives();

	/** Reclaim resources if any prior to exiting ... */
	public void dispose();

	/**
	 * Returns true if this operation operates on an underlying dataset
	 * collection.
	 * 
	 * @return <code>true</code> if the operation has an underlying dataset
	 *         collection; <code>false</code> otherwise.
	 */
	public boolean hasDatasetCollection();

	/**
	 * Retrieve the dataset that is associated with this particular operation.
	 * 
	 * @return The underlying dataset collection.
	 */
	public DatasetCollection getDatasetCollection();

	/**
	 * Initialize the operation based on the specified processing directives.
	 * The initialization will throw a ProcessingException is there are
	 * problems.
	 * 
	 * @param processingDirectives
	 *            The specified processing directives
	 * @throws ProcessingException
	 *             If there are problems initializing based on the specified
	 *             processing directives.
	 */
	public void initialize(Properties processingDirectives)
			throws ProcessingException;

	/**
	 * Execute the operation.
	 * 
	 * @throws ProcessingException
	 *             If there are problems executing the operation in question.
	 */
	public void execute() throws ProcessingException;

	/**
	 * Check if the operation has been initialized
	 * 
	 * @return <code>true</code> if the operation has been initialized;
	 *         <code>false</code> otherwise.
	 */
	public boolean isInitialized();

	/**
	 * Returns an indicator that indicates if the initialization needs to be
	 * performed. Some operations do not need any initializations prior to
	 * execution
	 * 
	 * @return <code>true</code> if the operation has needs to be initialized;
	 *         <code>false</code> otherwise.
	 */
	public boolean needsInitialization();

	/**
	 * This indicates if the operation has completed or not. For an operation
	 * whose execution profile indicates that the operation isStayAlive() the
	 * operation will be resident till such time that this flag has been set
	 * signifying that the operation is ready for teardown.
	 * 
	 * @return <code>true</code> if the operation has reached its termination
	 *         condition; <code>false</code> otherwise.
	 */
	public boolean terminationConditionReached();

	/**
	 * Check to see if this operation has an execution profile
	 * 
	 * @return <code>true</code> if the operation has an execution profile;
	 *         <code>false</code> otherwise.
	 */
	public boolean hasExecutionProfile();

	/**
	 * Retrieve the execution profile associated with this operation
	 * 
	 * @return The execution profile associated with the operation.
	 */
	public ExecutionProfile getExecutionProfile();

	/**
	 * A summarized String-based representation of the operation
	 * 
	 * @return The String representation of the operation.
	 */
	public String toString();

}
